<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Executing an ECLiPSe goal from Java and processing the result
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot044.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot041.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot046.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc85">8.4</A>&nbsp;&nbsp;Executing an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> goal from Java and processing the result</H2><UL>
<LI><A HREF="embroot045.html#toc42">Passing the goal parameter to <TT>rpc</TT></A>
<LI><A HREF="embroot045.html#toc43">Note: <B>yield/2</B>, <B>remote_yield/1</B> and <TT>rpc</TT></A>
<LI><A HREF="embroot045.html#toc44">Retrieving the results of an <TT>rpc</TT> goal execution</A>
<LI><A HREF="embroot045.html#toc45">More details about <TT>rpc</TT> goal execution</A>
</UL>

<A NAME="sec:ji-calling-goals"></A>
The <I>EclipseConnection</I> <A NAME="@default175"></A> interface
provides a single method <TT>rpc</TT><A NAME="@default176"></A> (Remote Predicate Call) for executing
goals in the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. This method takes as a parameter the goal to be
executed. How to construct this parameter is dealt with in Section
<A HREF="#sec:ji-rpc-parameter">8.4.1</A>. Section <A HREF="#sec:ji-rpc-return">8.4.2</A> explains
how to deal with the results returned by <TT>rpc</TT><A NAME="@default177"></A>. Finally, some more
details about the execution of the goal are given in Section
<A HREF="#sec:ji-goal-execution">8.4.3</A>. <BR>
<BR>
<A NAME="toc42"></A>
<H3 CLASS="subsection"><A NAME="htoc86">8.4.1</A>&nbsp;&nbsp;Passing the goal parameter to <TT>rpc</TT><A NAME="@default178"></A></H3>
<A NAME="sec:ji-rpc-parameter"></A>
There are main two variants of <TT>rpc</TT><A NAME="@default179"></A> which differ in the class of the
goal parameter.<BR>
<BR>
The simplest way to use <TT>rpc</TT><A NAME="@default180"></A> is to pass it an instance of <I>java.lang.String</I> which should be the goal as it would be typed into
the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> command line. Just like with the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> command line,
the goal can be a conjunction of several subgoals. An example of this
is the use of <TT>rpc</TT><A NAME="@default181"></A> in the example program <TT>QuickTest.java</TT>. Also please note a full stop is not necessary.<BR>
<BR>
The string-parameter <TT>rpc</TT><A NAME="@default182"></A> variant is somewhat inefficient and it
is also inflexible because creating goals dynamically, or goals
involving strings is tricky. It should really only be used for short
simple goals. A more flexible and efficient alternative is to invoke
<TT>rpc</TT><A NAME="@default183"></A>, passing it a parameter object which implements the <I>CompoundTerm</I> interface (discussed in Section
<A HREF="embroot044.html#sec:ji-atoms-and-terms">8.3.2</A>). In this case the term becomes the
goal. Here is an example of using this version of <TT>rpc</TT><A NAME="@default184"></A>, taken
from
<A HREF="../examples/JavaInterface/DataExample1.java"><TT>DataExample1.java</TT></A>.
<PRE CLASS="verbatim">
    CompoundTerm a_term = construct_term();

    // Get Eclipse to write the term to stdout and flush 
    eclipse.rpc(
                new CompoundTermImpl(",",
                              new CompoundTermImpl("write", 
                                            new Atom("output"), a_term),
                              new CompoundTermImpl("flush", new Atom("output"))
                              )
                );
</PRE>Using this variant is a bit more cumbersome (e.g. the creation of a
new <I>CompoundTermImpl</I> for the conjunction of goals in the above
example) but it would be useful for large goals constructed
dynamically. There are also a number of &#8220;convenience&#8221; <TT>rpc</TT><A NAME="@default185"></A>
methods, where instead of providing a <I>CompoundTerm</I>, you provide
the objects from which the term is made. See the API documentation for
more details of these variants.<BR>
<BR>
<A NAME="toc43"></A>
<H3 CLASS="subsection">Note: <A HREF="../bips/kernel/externals/yield-2.html"><B>yield/2</B></A><A NAME="@default186"></A>, <A HREF="../bips/kernel/externals/remote_yield-1.html"><B>remote_yield/1</B></A><A NAME="@default187"></A> and <TT>rpc</TT><A NAME="@default188"></A></H3>
The builtins <A HREF="../bips/kernel/externals/yield-2.html"><B>yield/2</B></A><A NAME="@default189"></A> and <A HREF="../bips/kernel/externals/remote_yield-1.html"><B>remote_yield/1</B></A><A NAME="@default190"></A> should not be
executed anywhere within an <TT>rpc</TT><A NAME="@default191"></A> goal, as they will cause the
goal to return prematurely.<BR>
<BR>
<A NAME="toc44"></A>
<H3 CLASS="subsection"><A NAME="htoc87">8.4.2</A>&nbsp;&nbsp;Retrieving the results of an <TT>rpc</TT><A NAME="@default192"></A> goal execution</H3>
<A NAME="sec:ji-rpc-return"></A>
The <TT>rpc</TT><A NAME="@default193"></A> method returns an object which implements <I>CompoundTerm</I>. This object is the Java representation of the goal term, with
the solution substitution applied to its variables. <BR>
<BR>
The solution substitution can be deconstructed using the returned <I>CompoundTerm</I>'s <TT>arg</TT> method. This method takes an integer (the argument
position) and returns an Object which is the Java representation of
the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> argument at that position.<BR>
<BR>
In the returned <I>CompoundTerm</I> instantiated variables are replaced
with their instantiations. Hence even if the variable was named in the
initial goal, its instantiation is identified in the returned goal by
its <I>position</I> rather than its name. Uninstantiated variables in
the returned <I>CompoundTerm</I> are represented using the Java <I>null</I>
token.<BR>
<BR>
If a variable in the <TT>rpc</TT> goal becomes instantiated to an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
data type which does not have an equivalent EXDR type (such as breal), then
in the returned <I>CompoundTerm</I> it will appear as the Java <I>null</I>
token.<BR>
<BR>
The following Java code is an example of how the returned <I>CompoundTerm</I>
can be deconstructed to extract the variable substitutions.
<PRE CLASS="verbatim">
...
    CompoundTerm result = eclipse.rpc("X = Q, Y is 2.1 + 7");

    // The top-level functor of the goal term is ",". 
    // The first and second arguments of the goal term are the two subgoals
    // and we can safely cast these as CompoundTerms.
    CompoundTerm firstGoal = (CompoundTerm) result.arg(1);
    CompoundTerm secondGoal = (CompoundTerm) result.arg(2);
    // X is the first argument of the first goal.
    Object firstGoalFirstArg = firstGoal.arg(1);
    // Y is the first argument of the second goal.
    Object secondGoalFirstArg = secondGoal.arg(1);

    System.out.println("X = "+firstGoalFirstArg);
    System.out.println("Y = "+secondGoalFirstArg);
...
</PRE>The output will be:
<PRE CLASS="verbatim">
X = null
Y = 9.1
</PRE>
<H4 CLASS="subsubsection">Other ways an <TT>rpc</TT><A NAME="@default194"></A> invocation can terminate</H4>
Apart from succeeding and returning a <I>CompoundTerm</I>, <TT>rpc</TT><A NAME="@default195"></A> can throw
exceptions. If the goal fails, an instance of <I>Fail</I> is
thrown. So to test for failure you must catch this exception. An
instance of <I>Throw</I> is thrown if ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> itself throws an
error.<BR>
<BR>
<A NAME="toc45"></A>
<H3 CLASS="subsection"><A NAME="htoc88">8.4.3</A>&nbsp;&nbsp;More details about <TT>rpc</TT><A NAME="@default196"></A> goal execution</H3>
<A NAME="sec:ji-goal-execution"></A>

<H4 CLASS="subsubsection">Variables</H4>
As explained in Section <A HREF="embroot044.html#sec:ji-variables-null">8.3.6</A>, ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
variables are always represented by the <I>null</I> token, when <TT>rpc</TT><A NAME="@default197"></A> is invoked with a <I>CompoundTerm</I> parameter. When used in an
<TT>rpc</TT><A NAME="@default198"></A> goal, each <I>null</I> token represents a different
variable. Using <I>CompoundTerm</I> you cannot represent a goal with
multiple occurrences of a single variable. So, for example the
following Java code will output <TT>q(b, b)</TT> for the first <TT>rpc</TT><A NAME="@default199"></A>
invocation and <TT>q(a, b)</TT> for the second.
<PRE CLASS="verbatim">
...

  eclipse.rpc("assert(q(a, b))");
  eclipse.rpc("assert(q(b, b))");

  System.out.println(eclipse.rpc("q(X, X)"));
  System.out.println(eclipse.rpc(new CompoundTermImpl("q", null, null)));

...
</PRE>

<H4 CLASS="subsubsection">Nondeterminism</H4>
The <TT>rpc</TT><A NAME="@default200"></A> feature does not support the handling of nondeterminism
in the execution of the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> goal. If the goal succeeds, control
is returned to Java immediately after the first solution to the goal
is found in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. All choice-points thereafter are ignored. So,
for example, although the first ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> goal below would leave
choice-points, it would be equal in effect to the second.
<PRE CLASS="verbatim">
...
result = eclipse.rpc("member(X, [1, 2, 3, 4, 5])");
...
result = eclipse.rpc("member(X, [1])");
</PRE>This is not a practical problem. It merely implies that if you are
using nondeterminism to generate multiple solutions, you should
collect these on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side using a meta-level built-in
predicate such as <TT>findall/3</TT> and then return the result to Java.<BR>
<BR>

<H4 CLASS="subsubsection">Concurrent invocations of <TT>rpc</TT><A NAME="@default201"></A></H4>
Note that the <TT>rpc</TT><A NAME="@default202"></A> method is <TT>synchronized</TT>. Therefore if,
while one Java thread is currently executing an <TT>rpc</TT><A NAME="@default203"></A> invocation,
a second Java thread tries to invoke the <TT>rpc</TT><A NAME="@default204"></A> method of the same
<I>EclipseConnection</I>, the second thread will block until the first
thread's <TT>rpc</TT><A NAME="@default205"></A> invocation returns.<BR>
<BR>

<H4 CLASS="subsubsection">Nested invocations of <TT>rpc</TT><A NAME="@default206"></A></H4>
During the execution of the <TT>rpc</TT><A NAME="@default207"></A> method, control
 is transferred to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. Due to the <I>QueueListener</I> feature
 <A NAME="@default208"></A> which is discussed in Section
 <A HREF="embroot046.html#sec:ji-using-queue-streams">8.5</A>, control is sometimes temporarily
 returned to Java before the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> execution has finished. It is
 possible for this Java code itself to invoke <TT>rpc</TT><A NAME="@default209"></A>, thus leading to nested <TT>rpc</TT><A NAME="@default210"></A>
 invocations. Nested <TT>rpc</TT><A NAME="@default211"></A> invocations should not
 cause any problems.<BR>
<BR>
<HR>
<A HREF="embroot044.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot041.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot046.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
